Cash In — Confirmation

Finalize a debt settlement. Presto reduces the driver's outstanding debt and records the institution as the collecting party.

info

Call this only after a successful Cash In — Initialization and after the driver has acknowledged the amount.

Overview

Confirmation is the point of no return for a Cash In. On 200 OK:

• The driver's outstanding_debt is permanently reduced by amount
• A settlement record is created against your institution for reconciliation
• The driver receives a notification in the Presto driver app

Endpoint details

Method: POST URL: /api/institutions/v1/drivers/debt/settlement/confirm Purpose: Reduce the driver's debt and record the settlement

Authentication required

All API calls require a valid bearer token. See Authentication.

Request specification

Headers

Header	Required	Description
Authorization	Yes	Bearer {token}
Content-Type	Yes	application/json
Idempotency-Key	Yes	UUID v4. Replaying the same key returns the original response instead of settling twice.

Request body

Parameter	Type	Required	Description
transaction_reference	string	Yes	The reference returned by the init call

Example request

// Headers:
// Authorization: Bearer {token}
// Content-Type: application/json
// Idempotency-Key: 8f14e45f-ceea-467a-9c2e-6f9a1b2c3d4e

{
  "transaction_reference": "DS-9F3K2LQ7XB"
}

Response specification

Success response

200 OK

{
  "data": {
    "status": "completed",
    "type": "debt_settlement",
    "transaction_reference": "DS-9F3K2LQ7XB",
    "amount": 200.000,
    "currency": "LYD",
    "timestamp": "2026-09-14T14:30:45Z",
    "institution_reference": "IZI-2026-0914-000187",
    "driver": {
      "uid": "10432",
      "name": "MOH... OK...",
      "phone": "218920000000"
    },
    "outstanding_debt_after": 140.500
  }
}

Response fields

Field	Type	Description
status	string	"completed"
type	string	Always "debt_settlement"
transaction_reference	string	Reference of the completed settlement
amount	number	Amount settled
currency	string	Currency of the amount
timestamp	string	ISO 8601 date and time the settlement was recorded
institution_reference	string	Your own reference from the init call, echoed back unchanged
driver	object	Driver whose debt was reduced
outstanding_debt_after	number	Remaining debt after the settlement

Error responses

404 Not Found

{
  "message": "Transaction reference not found"
}

409 Conflict — already finalized

{
  "message": "Transaction is not pending"
}

410 Gone — reservation expired

{
  "message": "Transaction has expired"
}

422 Unprocessable Content — the driver's debt changed since init

{
  "message": "The amount may not be greater than the outstanding debt.",
  "errors": {
    "amount": [
      "The amount may not be greater than the outstanding debt."
    ]
  }
}

500 Internal Server Error

{
  "message": "Transaction processing failed"
}

Error handling

Common errors

HTTP Status	Error Type	Example Message	When it Occurs / Resolution
404	Not found	{"message": "Transaction reference not found"}	Wrong or unknown reference. Do not take the cash.
409	Not pending	{"message": "Transaction is not pending"}	Already confirmed or already voided. Query transaction status to find out which.
410	Expired	{"message": "Transaction has expired"}	More than 15 minutes since init. Re-run init.
422	Balance changed	{"message": "The amount may not be greater than the outstanding debt."}	The driver's debt was reduced through another channel after init. The transaction is now failed. Return the cash.
500	Internal server error	{"message": "Transaction processing failed"}	Outcome unknown. Query transaction status before returning or keeping the cash.

Never resolve a timeout by guessing

If confirm times out, the settlement may or may not have been recorded. Query transaction status with the same transaction_reference and act on that result. Retrying confirm is safe only with the same Idempotency-Key.

Implementation tips

Best practices

• Record transaction_reference, timestamp and outstanding_debt_after against your own receipt for end-of-day reconciliation.
• Print a receipt showing the Presto reference so the driver can raise a dispute with either party.
• Use exponential backoff for 5xx retries, always with the same idempotency key.

Next steps

Verify or reconcile the settlement with the Transaction Status endpoint.